home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1996 #15 / Monster Media Number 15 (Monster Media)(July 1996).ISO / utils / chang604.zip / CHANGE.DOC < prev    next >
Text File  |  1996-04-20  |  15KB  |  346 lines
  1. CHANGE.DOC                           1                         Revised: 04/20/96
  2.  
  3. Program written by:
  4.                         Bruce Guthrie
  5.                         Room H-4885
  6.                         U.S. Dept of Commerce/ESA/STAT-USA
  7.                         Washington, DC 20230
  8.  
  9.                         voice: (202) 482-3234
  10.                         e-mail: bguthrie@doc.gov
  11.  
  12. You may freely copy and re-distribute this program; however, the U.S. Department
  13. of Commerce neither guarantees nor assures compatibility of the program with all
  14. computer software or hardware.
  15.  
  16. Foreign users:  Please provide an Internet e-mail address in all correspondence.
  17.  
  18.  
  19. The CHANGE.EXE program allows you to make changes in binary or text files of any
  20. size.  Features:
  21.  
  22.   * Can handle files of any size provided you have enough room on your disk
  23.     to hold a copy of resulting file.
  24.   * Can be used to change text files or binary files.
  25.   * Can be used to remove trailing spaces from a file.
  26.   * Can specify different lengths for the input strings and the output strings.
  27.   * Can specify that the changes only be done in lines that include a certain
  28.     character string.  This selection string can be case-insensitive.
  29.   * Can handle up to 30 change requests at a time.
  30.   * Can specify the input/output strings as ASCII characters, hexadecimal
  31.     values, or as decimal values.
  32.   * Handles the changes fairly quickly.
  33.   * Can either replace the original file with the resulting file or else
  34.     create a new changed file (using /Noutfile specification).
  35.   * Changes can be verified before they are made.
  36.   * Changes can be entered in any of the following ways:
  37.       - from the command line (one TO/FROM pair allowed)
  38.       - interactively (one TO/FROM pair allowed)
  39.       - from a controlfile (up to 30 TO/FROM pairs allowed)
  40.   * Boolean operators can be used if the TO/FROM pair is specified from the
  41.     command line; for example:
  42.       CHANGE TEST.TXT /FROM One /TO Many /IN Apples OR Oranges
  43.   * The input file specification can include standard DOS wildcards or an
  44.     external file (@listfile) containing the files to be processed (although
  45.     either prohibits using the /Noutfile feature).
  46.   * The input change specification can end with "*" in which case all
  47.     subsequent characters are changed to the end of the line.
  48.  
  49.  
  50. Specifying parameters:
  51.  
  52. Parameters for this program can be set in the following ways.  The last  setting
  53. encountered always wins:
  54.   - Read from an *.INI file (see BRUCEINI.DOC file),
  55.   - Through the use of an environmental variable (SET CHANGE=whatever), or
  56.   - From the command line (see "Syntax" below)
  57.  
  58.  
  59.  
  60. CHANGE.DOC                           2                         Revised: 04/20/96
  61.  
  62. To/From/In Specifications:
  63.  
  64. The CHANGE program allows you to specify three parts to a change request:
  65.  
  66.   * The text to be replaced
  67.   * The text to replace it with
  68.   * Optionally, a string which the line must contain before the change is made
  69.  
  70. For example, in the following two lines:
  71.  
  72.         The quick brown fox jumped over
  73.         the lazy brown dog.
  74.  
  75. the program allows you to replace the string "brown" with the string "red"  only
  76. in lines that contain the string "fox" (so "brown fox" becomes "red fox").  This
  77. would change the "brown" in the first line but not the one in the second line.
  78.  
  79. In order to enter your change request(s), you can use one of three methods:
  80.  
  81.   * Enter it from the command line using /FROM string, /TO string, /IN string
  82.   * Let the program prompt you for the /FROM and /TO specification (in which
  83.     case no /IN string can be provided)
  84.   * Use a control file
  85.  
  86. The control file is a regular ASCII text file (created with any text editor). It
  87. can contain up to 30 change requests (the other two approaches  only  allow  for
  88. one).  Each line of the control file should consist of records of  one  of  four
  89. record types:
  90.  
  91.   * blank lines or those beginning with semi-colons, colons, or single quotes
  92.     are treated as comments.
  93.   * lines beginning with "-F" or "-f" provide FROM options.
  94.   * lines beginning with "-T" or "-t" provide TO options.
  95.   * lines beginning with "-I" or "-i" provide IN options.  These are optional;
  96.     if not provided, all lines will be searched for the FROM string.  Any
  97.     IN request forces /TEXT mode to be invoked
  98.  
  99. If more than one set of FROM/TO/IN records is  provided,  the  -F  specification
  100. must  precede  the  others.   Each  option  is  local  to  a  given   FROM/TO/IN
  101. specification.  For example:
  102.  
  103.         ; Sample control file
  104.         -FPRINT
  105.         -TPrinting
  106.         -I"
  107.         -fUSING
  108.         -tused
  109.  
  110. contains two FROM/TO/IN specifications.  "PRINT" will be changed  to  "Printing"
  111. in any line with a double quote.  "USING" will  be  changed  to  "used"  in  all
  112. lines; no -I option is applied for the second FROM/TO/IN specification.
  113.  
  114.  
  115. CHANGE.DOC                           3                         Revised: 04/20/96
  116.  
  117. If you want to specify your from/to request from the command  line  and  any  of
  118. your strings contains one or more spaces, enclose the string in double quotation
  119. marks.  For example:
  120.  
  121.         CHANGE BUGBUNNY.TXT /FROM "Elmer Fudd" /TO "Daffy Duck"
  122.  
  123. The FROM/TO/IN specifications can include any text characters.   They  can  also
  124. contain ASCII codes, created either using the Alt key in  combination  with  the
  125. numeric keypad (e.g.  Alt-228 to get a Sigma character) or else by  embedding  a
  126. hexadecimal code (in the form &Hxx) or a decimal code (in the form \nnn) in  the
  127. text.  These codes are described in the  BRUCEHEX.DOC  file.   For  example,  to
  128. change a double carriage return/line feed to a single carriage return/line feed,
  129. you could say:
  130.  
  131.         -F&H0D0A0D0A
  132.         -T&H0D0A
  133.  
  134. (Note that the above example would require you to use  the  /BINARY  option--the
  135. default-- since the lines encountered will extend beyond line boundaries.)
  136.  
  137. If you need to follow a hexadecimal specification with normal  text  characters,
  138. follow the hex spec with one space (which CHANGE will ignore).  For example,
  139.  
  140.         -F&H0c Hi!
  141.         -T&H0d0a Bye!
  142.  
  143. DOS considers certain characters ("|" and ">") to be pipe  characters  and  will
  144. strip them away from the command line before CHANGE gets them.  If you  need  to
  145. specify a change that includes these characters and you want to use the  command
  146. line for it, use the  hexadecimal  or  decimal  codes  instead.   Alternatively,
  147. putting them in quotes seems to usually work.
  148.  
  149. If the "/FROM string" specification ends with an asterisk (e.g. "/FROM BRUCE*"),
  150. the program will look for any instance of the string  before  the  asterisk  and
  151. replace that  string  and  all  subsequent  characters  in  the  line  with  the
  152. designated "/TO string".  Asterisks embedded within the string  (as  opposed  to
  153. being the trailing character of the string) will be read as regular  characters.
  154. If you actually want to replace an asterisk as a  trailing  character,  use  the
  155. &Hxx or \nnn conventions.  Specifying a wildcard like this puts you  into  /TEXT
  156. mode automatically.  Wildcards cannot be used in the "/TO string" specification.
  157.  
  158. To remove a string entirely, use  the  -T  without  anything  after  it  or  use
  159. "-TNULL" or "/TO NULL" from the command line.
  160.  
  161. As far as case-sensitivity is concerned, the /FROM and  /IN  specifications  are
  162. case-sensitive unless /I  is  specified.   The  /TO  specification  is  *always*
  163. case-sensitive.
  164.  
  165.  
  166.  
  167. CHANGE.DOC                           4                         Revised: 04/20/96
  168.  
  169. Syntax:
  170.  
  171.     CHANGE { filespec | @listfile }
  172.       [ /Cctlfile | /FROM string /TO string [ /IN search ] ]
  173.       [ /LINES { line1-line2 | line1 linect } ... ] [ /V | /-V ] [ /I | /-I ]
  174.       [ /Noutfile [ /OVERWRITE | /-OVERWRITE | /OVERASK ] ]
  175.       [ /Iinitfile ] [ /Frptfile ] [ /Ttempfile ] [ /TRIM | /-TRIM ]
  176.       [ /BINARY | /TEXT ] [ /VERIFY | /-VERIFY ] [ /Q ] [ /? ] [ /?&H ]
  177.  
  178. where:
  179.  
  180. "filespec" tells the routine which file or files are to be  processed.   It  can
  181. include path information if desired.  It can also include standard DOS wildcards
  182. as long as the /Noutfile parameter is not specified.  If a  /Noutfile  parameter
  183. is not provided, the input files are overwritten by the results of this program.
  184. If you'd like to process a lot of files and still create new files, use the  DOS
  185. FOR command instead.  Try something like this:
  186.  
  187.         FOR %A IN (*.TXT) DO CHANGE %A /FROM "A" /TO "B" /N\TEMP\%A
  188.  
  189. "@listfile" allows you to have a variety of file specifications saved in a  text
  190. file named "listfile".  Each line  in  the  file  should  consist  of  one  file
  191. specification, each of which can include a path and wildcards if desired.  Blank
  192. lines and lines beginning with semi-colons, colons, or quotes are ignored.
  193.  
  194. "/Cctlfile" specifies a control file with  the  change  commands  to  make.  See
  195. "To/From/In Specifications" above.
  196.  
  197. "/FROM string /TO string [ /IN search ]"  allows  you  to  specify  the  from/to
  198. parameters on the control line.  See "To/From/In Specifications" above.
  199.  
  200. "/Iinitfile" says to read an initialization file with the file name  "initfile".
  201. The file specification *must* contain a period.  Initfiles are described in  the
  202. BRUCEINI.DOC file.  Initially defaults to "/ICHANGE.INI".
  203.  
  204. "/LINES line1-line2" says to restrict the search to lines between  line  numbers
  205. line1 and line2 inclusive.  You can have multiple line  requests  in  any  order
  206. such as "/LINES 1-10 90-100 30-50".  The  routine  skips  all  lines  after  the
  207. largest line number is encountered.  Defaults to "/LINES 1-9999999".
  208.  
  209. "/LINES line1 linect" says to restrict the search to lines beginning with  line1
  210. and continuing for a total of linect lines.  So "/LINES 10 20" is  actually  the
  211. same as "/LINES 10-29".
  212.  
  213. "/V" says to find those items that do NOT match the specification.
  214.  
  215. "/-V" is the opposite of /V and is typically the default.
  216.  
  217. "/I" says to make it a case-insensitive search.
  218.  
  219. "/-I" is the opposite of /I and is typically the default.
  220.  
  221. "/Noutfile" is the name of the new file  to  create.   If  a  /Noutfile  is  not
  222. specified, the source document (infile) will be replaced by the changed file.
  223.  
  224.  
  225. CHANGE.DOC                           5                         Revised: 04/20/96
  226.  
  227. "/OVERWRITE" says to write over the outfile (if requested) if it exists already.
  228.  
  229. "/-OVERWRITE" says to abort if the outfile exists already.
  230.  
  231. "/OVERASK" says to ask if the outfile exists already.  This is the default.
  232.  
  233. "/Frptfile" is the name of a file to contain all changed lines.  This allows you
  234. to see what the lines were changed to for verification  purposes.   This  option
  235. automatically invokes /TEXT.  The report file is always appended to so new lines
  236. are written at the end of any existing report file.
  237.  
  238. "/Ttempfile" is the name of the temporary file to create.   The  actual  changes
  239. are written to a temp file and then the source file is replaced  with  the  temp
  240. file is everything works and there were actually changes  to  be  found  in  the
  241. source document.  By default, the temp file is written to the same path  as  the
  242. input file.  The temporary file will be as big as the final  file  is.   If  you
  243. don't have enough room for it  to  be  on  your  source  disk,  specify  another
  244. temporary file name with a different path (e.g. "/TG:\TEMP.TXT").
  245.  
  246. "/TRIM" says to remove trailing spaces from the end of each line.  Automatically
  247. forces you into TEXT mode.
  248.  
  249. "/-TRIM" is the opposite of /TRIM and is the default.
  250.  
  251. "/TEXT" puts you into TEXT mode.  TEXT mode means that all data in the file  are
  252. read in and processed as separate text records.  Alternatively, the file can  be
  253. processed in BINARY mode in which case  the  file  is  read  in  in  12,000-byte
  254. blocks. BINARY mode is quicker and is required for EXE and COM files.  TEXT mode
  255. presents some information  like  the  number  of  lines  in  your  file  and  is
  256. *required* if you specify any of the following options:
  257.  
  258.         * an IN (or -I) request
  259.         * /LINES
  260.         * /Frptfile
  261.         * /TRIM
  262.         * /VERIFY
  263.  
  264. "/BINARY" is the opposite of TEXT mode.   It's  faster  than  TEXT  and  is  the
  265. default for CHANGE.  It is overridden if  you  specify  certain  options  listed
  266. above.
  267.  
  268. "/VERIFY" says to prompt you before  changing  any  lines.   You  are  asked  to
  269. confirm that you in fact want to  make  each  change  requested.   Automatically
  270. forces you into TEXT mode.
  271.  
  272. "/-VERIFY" is the opposite of /VERIFY and is the default.
  273.  
  274. "/Q" turns off the line-by-line status messages.
  275.  
  276. "/?" or "/HELP" or "HELP" shows you the syntax for the command.
  277.  
  278. "/?&H" gives you a hexadecimal and decimal conversion table.
  279.  
  280.  
  281.  
  282. CHANGE.DOC                           6                         Revised: 04/20/96
  283.  
  284. For search, the syntax is:
  285.  
  286.   [ ( ]... search_item [ boolean [ ( ]... search_item [ ) ]...] [ ) ]...
  287.  
  288. where:
  289.  
  290.   ( and )     are used to group items
  291.   search_item is shown below
  292.   boolean     is AND, OR, or XOR (NOT is included with search_item)
  293.  
  294. for search_item, the syntax is:
  295.  
  296.   [ NOT ]  "string" [ column ]
  297.  
  298. where:
  299.   NOT         is obvious
  300.   string      the string to search; the quotation marks are typically not
  301.               required unless the string contains a space or a reserved word
  302.   column      is the column in which the string must be found.
  303.  
  304. So, let's cover some examples:
  305.  
  306.         CHANGE TEST.TXT /FROM Apple /TO Banana /IN "Bugs Bunny" OR "Elmer Fudd"
  307.  
  308. Changes the string "Apple" to "Banana" in any lines that have  either  the  text
  309. "Bugs Bunny" or "Elmer Fudd" in them.
  310.  
  311.         CHANGE TEST2.TXT /FROM Bugs /TO Bunny /IN (Apples or Oranges) AND NOT
  312.            Pears /LINES=1-1000 /COLS=1/5
  313.  
  314. Changes "Bugs" to "Bunny" in the first thousand lines of  TEST2.TXT.   The  line
  315. itself must contain the words "Apples" or "Oranges" in them and  any  lines  are
  316. ignored that contain "Pears".  Note that the quotes around the search words  are
  317. not required unless the words include spaces or unless they  could  be  confused
  318. with some other keywords.  "CHANGE TEST3.TXT /FROM Bugs /TO Bunny /IN OR OR AND"
  319. might cause the program to get confused since "OR" and "AND", which you want  to
  320. look for as also keywords.
  321.  
  322.         CHANGE /I TEST.TXT /FROM One /TO Many /IN "Bugs Bunny" AND Martians
  323.  
  324. This changes "One" to "Many" is any lines that contain  both  "Bugs  Bunny"  and
  325. "Martians".  The search is case-insensitive so lines with  either  "BUGS  BUNNY"
  326. and "Bugs Bunny" will be changed.
  327.  
  328. NOTE:  THIS EXTENDED SEARCHING CAPABILITY IS SUPPORTED  ONLY  FOR  /IN  REQUESTS
  329. MADE FROM THE COMMAND LINE.  IT IS NOT SUPPORTED IN EITHER THE CTLFILE OR IN THE
  330. INTERACTIVE TO/FROM SELECTION MODE.
  331.  
  332.  
  333. CHANGE.DOC                           7                         Revised: 04/20/96
  334.  
  335. Return codes:
  336.  
  337. CHANGE returns the following ERRORLEVEL codes:
  338.  
  339.         0 = no problems, changes made
  340.         1 = no problems, nothing found to change
  341.       253 = routine aborted early
  342.       254 = internal problems
  343.       255 = syntax problems, file not found, or /? requested
  344.  
  345. 
  346.